OpenEdge Development:<br />Programming Interfaces 4GL for programming sockets

Table 17–1 lists the 4GL elements that are either valid only for working with sockets or have special application in socket programming. The remaining sections in this chapter explain how to use these elements.

Table 17–1: 4GL for programming sockets
4GL element	Description
BYTES-READ	An `INTEGER` attribute on the socket object handle that returns the number of bytes read during the last invocation of the socket `READ( )` method. If the last `READ( )` method call on the socket failed, this attribute returns 0.
BYTES-WRITTEN	An `INTEGER` attribute on the socket object handle that returns the number of bytes written during the last invocation of the socket `WRITE( )` method. If the last `WRITE( )` method call on the socket failed, this attribute returns 0.
CONNECT	An event received on a server socket object handle that indicates that a socket client is trying to connect. This event, if handled by an I/O-blocking or `PROCESS EVENTS` statement, executes any `CONNECT` event procedure defined for the server socket object. You can use this event procedure to obtain the socket object with which the client is communicating.
CONNECT (`connection-parameters` )	A method on the socket object handle that connects a socket handle to a specified TCP/IP port on a specified host.
CONNECTED( )	A method on the socket object handle that indicates if a socket handle is currently connected to a port.
CREATE SERVER-SOCKET `server-socket-handle`	A statement that creates a server socket object with all attributes set to their default values, and stores its handle in a `HANDLE` variable.
CREATE SOCKET `socket-handle`	A statement that creates a socket object with all attributes set to their default values and stores its handle in a `HANDLE` variable.
DEFINE INPUT PARAMETER `socket-handle`	A statement that defines the single `INPUT` parameter to the `CONNECT` event procedure (specified using the `SET-CONNECT-PROCEDURE( )` method). This parameter returns the handle to the socket object created when a socket server receives a `CONNECT` event, and which the socket server uses to communicate with the corresponding socket client.
DELETE OBJECT `handle`	A statement that you can use to delete a handle, including socket and server socket object handles. To delete a connected socket object, you must first disconnect it using the `DISCONNECT( )` method. To delete a server socket object enabled to listen for connections, you must first disable it using the `DISABLE-CONNECTIONS( )` method.
DISABLE-CONNECTIONS( )	A method on the server socket object handle that indicates that new connections are no longer accepted on the server socket.
DISCONNECT( )	A method on the socket object handle that terminates the connection between the socket object and the port to which it is connected.
ENABLE-CONNECTIONS ( `connection-parameters` )	A method on the server socket object handle that specifies the TCP/IP port that Progress uses to listen for new connections. Once called, Progress automatically listens for and accepts new connections on the specified port. `ENABLE-CONNECTIONS()` also lets you specify the length of the pending-connection queue.
FIRST-SERVER-SOCKET	A `HANDLE` attribute on the `SESSION` object handle that returns the handle to the first entry in the chain of server socket handles for the session. Note that you can have only one server socket object in the list enabled to listen for events at one time.
FIRST-SOCKET	A `HANDLE` attribute on the `SESSION` object handle that returns the handle to the first entry in the chain of socket handles for the session.
GET-BYTES-AVAILABLE( )	A method on the socket object handle that indicates the number of bytes available for reading from the socket.
GET-SOCKET-OPTION ( `option-name` )	A method on the socket object handle that returns the specified TCP socket option. Progress supports the following options: `TCP-NODELAY` `SO-LINGER` `SO-KEEPALIVE` `SO-REUSEADDR` `SO-SNDBUF` `SO-RCVBUF` `SO-RCVTIMEO` For more information on these options, see the OpenEdge Development: Progress 4GL Reference and your TCP documentation.
LAST-SERVER-SOCKET	A `HANDLE` attribute on the `SESSION` object handle that returns the handle to the last entry in the chain of server socket handles for the session. Note that you can have only one server socket object in the list enabled to listen for events at one time.
LAST-SOCKET	A `HANDLE` attribute on the `SESSION` object handle that returns the handle to the last entry in the chain of socket handles for the session.
LOCAL-HOST	A `CHARACTER` attribute on the socket object handle that returns the IP address on the local machine where the socket object is connected.
LOCAL-PORT	An `INTEGER` attribute on the socket object handle that returns the local port number of the socket object.
NEXT-SIBLING	A `HANDLE` attribute on the socket and server socket object handle that returns the next entry in the list of socket or server socket handles created for the current OpenEdge session.
MEMPTR	The Progress data type used by the socket handle `READ( )` and `WRITE( )` methods to read and write data on a socket. A `MEMPTR` expression defines a memory region whose size you must allocate in bytes. `MEMPTR` functions and statements allow you to read and write data between most other Progress data types and the specified memory region. For more information on the `MEMPTR` data type, see Chapter 8, " Introduction to External Program Interfaces."
PREV-SIBLING	A `HANDLE` attribute on the socket and server socket object handle that returns the previous entry in the list of socket or server socket handles created for the current OpenEdge session.
PROCESS EVENTS	A statement that you can use to handle any pending `CONNECT` or `READ-RESPONSE` events. You can also use any I/O-blocking statement, such as the `WAIT-FOR` statement.
READ( `memptr-expression` , `position` , `bytes-to-read` [ , `mode` ] )	A method on the socket object handle that reads data from the specified socket. The method specifies the `MEMPTR` memory region and byte position within the region to store the data, a number of bytes to read (and store) from the socket, and a read mode. The read mode indicates if the exact specified number of bytes must be read or up to the specified number of bytes can be read.
READ-RESPONSE	An event received on a socket object handle indicating that data is waiting on the socket to be read. This event, if handled by an I/O-blocking or `PROCESS EVENTS` statement, executes any `READ-RESPONSE` event procedure defined for the socket object. You can use this event procedure if you want to read data from the socket in an event-driven manner.¹
REMOTE-HOST	A `CHARACTER` attribute on the socket object handle that returns the IP address of the remote machine with which a connected socket object is communicating.
REMOTE-PORT	An `INTEGER` attribute on the socket object handle that returns the number of the port on the remote machine with which a connected socket object is communicating.
SELF	A system handle that returns the handle of the object on which an event is handled in the context of an event procedure. In a `CONNECT` event procedure, this is the handle to the server socket that is responding to a `CONNECT` event. In a `READ-RESPONSE` event procedure, this is the handle to the socket that is responding to a `READ-RESPONSE` event.
SENSITIVE	A `LOGICAL` attribute on the socket and server socket object handle that indicates whether the object can receive events. Set to `TRUE` (receive events) by default.
Server socket object handle	A handle to a server socket object. This object allows you to listen for and accept TCP/IP connections on a given port.
SET-CONNECT-PROCEDURE( `event-internal-procedure` [ , `procedure-context` ] )	A method on the server socket object handle that specifies the name of an internal procedure (`CONNECT event procedure`) to invoke when a `CONNECT` event occurs.
SET-READ-RESPONSE -PROCEDURE( `event-internal-procedure` [ , `procedure-context` ] )	A method on the socket object handle that specifies the name of an internal procedure (`READ-RESPONSE event procedure`) to invoke when a `READ-RESPONSE` event occurs.
Socket object handle	A handle to a socket object. This object allows you to read or write data on a TCP/IP socket and to perform other TCP/IP socket actions.
SET-SOCKET-OPTION ( `name`, `arguments` )	A method on the socket object handle that sets the specified TCP socket option. Progress supports the following options: `TCP-NODELAY` `SO-LINGER` `SO-KEEPALIVE` `SO-REUSEADDR` `SO-SNDBUF` `SO-RCVBUF` `SO-RCVTIMEO` For more information on these options, see the OpenEdge Development: Progress 4GL Reference and your TCP documentation.
SSL-SERVER-NAME	A `CHARACTER` attribute on the socket object handle that returns the SSL server’s X.500 Subject name field after any SSL session has been established.
TYPE	A `CHARACTER` attribute on the socket and server socket object handle that returns the handle type, which is `SERVER-SOCKET` for a server socket handle and `SOCKET` for a socket handle.
WAIT-FOR ...	A statement that you can use to handle any pending `CONNECT` or `READ-RESPONSE` events. You can also use `PROCESS EVENTS` or any other I/O-blocking statement, such as the `PROMPT-FOR` statement, to handle the events. When a `CONNECT` or `READ-RESPONSE` event occurs in the context of these statements, any `CONNECT` or `READ-RESPONSE` event procedure specified for the corresponding handle is executed.
WRITE( `memptr-expression` , `position` , `bytes-to-write` )	A method on the socket object handle that writes data to the specified socket. The method specifies the `MEMPTR` memory region and byte position within the region from which to write the data, as well as the number of bytes to write from the region.

¹A socket handle receives a READ-RESPONSE event under the same conditions that cause the TCP/IP select function to indicate that a socket is ready to receive results. However, in the 4GL, you must read data on the socket to continue to receive the event. For more information, see the "Data detection using the event-driven model" section.